<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
<!-- creator-projects-custom-wizards-xml.qdoc -->
  <title>Adding XML-Based Wizards | Qt Creator Manual</title>
  <link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
  <script type="text/javascript">
    document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
    // loading style sheet breaks anchors that were jumped to before
    // so force jumping to anchor again
    setTimeout(function() {
        var anchor = location.hash;
        // need to jump to different anchor first (e.g. none)
        location.hash = "#";
        setTimeout(function() {
            location.hash = anchor;
        }, 0);
    }, 0);
  </script>
</head>
<body>
<div class="header" id="qtdocheader">
  <div class="main">
    <div class="main-rounded">
      <div class="navigationbar">
        <table><tr>
<td ><a href="index.html">Qt Creator Manual</a></td><td >Adding XML-Based Wizards</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="index.html">Qt Creator Manual 4.11.1</a></td>
        </tr></table>
      </div>
    </div>
<div class="content">
<div class="line">
<div class="content mainContent">
  <link rel="prev" href="creator-project-wizards-json.html" />
  <link rel="next" href="creator-version-control.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="creator-project-wizards-json.html">Adding JSON-Based Wizards</a>
<span class="naviSeparator">  &#9702;  </span>
<a class="nextPage" href="creator-version-control.html">Using Version Control Systems</a>
</p><p/>
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#creating-xml-based-project-wizards">Creating XML-Based Project Wizards</a></li>
<li class="level1"><a href="#creating-class-wizards">Creating Class Wizards</a></li>
<li class="level1"><a href="#supported-widgets">Supported Widgets</a></li>
<li class="level2"><a href="#path-choosers">Path Choosers</a></li>
<li class="level2"><a href="#check-boxes">Check Boxes</a></li>
<li class="level2"><a href="#text-editors">Text Editors</a></li>
<li class="level1"><a href="#processing-template-files">Processing Template Files</a></li>
<li class="level1"><a href="#pre-defined-standard-variables">Pre-defined Standard Variables</a></li>
<li class="level1"><a href="#validating-user-input">Validating User Input</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Adding XML-Based Wizards</h1>
<span class="subtitle"></span>
<!-- $$$creator-project-wizards-xml.html-description -->
<div class="descr"> <a name="details"></a>
<p><b>Note: </b>We recommend that you create <a href="creator-project-wizards-json.html">JSON-Based wizards</a> instead. XML wizards are deprecated and support for them will be removed in future versions of Qt Creator.</p><p>To see examples of XML-based wizards, select <b>File</b> &gt; <b>New File or Project</b> &gt; <b>Library</b>. For each wizard, an icon (1), a display name (2), and a description (3) are displayed.</p>
<p class="centerAlign"><img src="images/qtcreator-custom-project-wizards.png" alt="&quot;The New dialog&quot;" /></p><p>Files can be generated by using <a href="creator-project-wizards-xml.html#processing-template-files">templates</a>.</p>
<p>XML-based wizard template directories contain an XML configuration file called wizard.xml and the template source files.</p>
<a name="creating-xml-based-project-wizards"></a>
<h2 id="creating-xml-based-project-wizards">Creating XML-Based Project Wizards</h2>
<p>To create an XML-based project wizard:</p>
<ol class="1" type="1"><li>Make a copy of a folder in the <code>share/qtcreator/templates/wizards/</code> folder that contains an XML-based wizard (<code>codesnippet</code>, <code>qtcreatorplugin</code>, or <code>qtquick2-extension</code>).</li>
<li>Modify the wizard.xml file.</li>
<li>The following code determines the type of the wizard and its place in the <b>New</b> dialog:<pre class="cpp">

  <span class="operator">&lt;</span>wizard version<span class="operator">=</span><span class="string">&quot;1&quot;</span> kind<span class="operator">=</span><span class="string">&quot;project&quot;</span>
  <span class="keyword">class</span><span class="operator">=</span><span class="string">&quot;qmakeproject&quot;</span> firstpage<span class="operator">=</span><span class="string">&quot;10&quot;</span>
  id<span class="operator">=</span><span class="string">&quot;A.HelloWorld&quot;</span> category<span class="operator">=</span><span class="string">&quot;B.CustomProjects&quot;</span><span class="operator">&gt;</span>

</pre>
<ul>
<li><code>version</code> is the version of the file contents.</li>
<li><code>kind</code> specifies the type of the wizard: <code>project</code> or <code>class</code>.</li>
<li><code>class</code> specifies the type of the project. This attribute is optional. Use the value <code>qmakeproject</code> to add Qt specific pages.</li>
<li><code>firstpage</code> specifies the place of the new page in the standard project wizard. The value 10 ensures that the custom page appears after the standard pages, as the last page of the wizard.</li>
<li><code>id</code> is the unique identifier for your wizard. The letter specifies the position of the wizard within the <code>category</code>. The HelloWorld wizard appears as the first wizard in the second category in the <b>New</b> dialog.</li>
<li><code>category</code> is the category in which to place the wizard in the list. The letter specifies the position of the category in the list in the <b>New</b> dialog.</li>
</ul>
</li>
<li>The following code specifies the icon and text that appear in the <b>New</b> dialog:<pre class="cpp">

  <span class="operator">&lt;</span>icon<span class="operator">&gt;</span>console<span class="operator">.</span>png<span class="operator">&lt;</span><span class="operator">/</span>icon<span class="operator">&gt;</span>
  <span class="operator">&lt;</span>description<span class="operator">&gt;</span>Creates a hello<span class="operator">-</span>world<span class="operator">-</span>project with custom message<span class="operator">.</span><span class="operator">&lt;</span><span class="operator">/</span>description<span class="operator">&gt;</span>
  <span class="operator">&lt;</span>description xml:lang<span class="operator">=</span><span class="string">&quot;de&quot;</span><span class="operator">&gt;</span>Erzeugt ein Hello<span class="operator">-</span>Welt<span class="operator">-</span>Projekt mit einer Nachricht<span class="operator">.</span><span class="operator">&lt;</span><span class="operator">/</span>description<span class="operator">&gt;</span>
  <span class="operator">&lt;</span>displayname<span class="operator">&gt;</span>Hello World<span class="operator">&lt;</span><span class="operator">/</span>displayname<span class="operator">&gt;</span>;
  <span class="operator">&lt;</span>displayname xml:lang<span class="operator">=</span><span class="string">&quot;de&quot;</span><span class="operator">&gt;</span>Hallo Welt<span class="operator">&lt;</span><span class="operator">/</span>displayname<span class="operator">&gt;</span>;
  <span class="operator">&lt;</span>displaycategory<span class="operator">&gt;</span>Custom Projects<span class="operator">&lt;</span><span class="operator">/</span>displaycategory<span class="operator">&gt;</span>
  <span class="operator">&lt;</span>displaycategory xml:lang<span class="operator">=</span><span class="string">&quot;de&quot;</span><span class="operator">&gt;</span>Benutzerdefinierte Projekte<span class="operator">&lt;</span><span class="operator">/</span>displaycategory<span class="operator">&gt;</span>

</pre>
<ul>
<li><code>displayCategory</code> appears in the <b>New</b> dialog, under <b>Projects</b>.</li>
<li><code>icon</code> appears next to the <code>displayName</code> in the middle panel when <code>displayCategory</code> is selected.</li>
<li><code>description</code> appears in the right-most panel when <code>displayCategory</code> is selected.<p>You can add translations as values for the text elements. Specify the target language as an attribute for the element. Use locale names (<a href="http://doc.qt.io/qt-5/qlocale.html">QLocale</a>). For example, <code>xml:lang=&quot;de&quot;</code>.</p>
</li>
</ul>
</li>
<li>The following code specifies the files to add to the project:<pre class="cpp">

  <span class="operator">&lt;</span>files<span class="operator">&gt;</span>
      <span class="operator">&lt;</span>file source<span class="operator">=</span><span class="string">&quot;main.cpp&quot;</span> openeditor<span class="operator">=</span><span class="string">&quot;true&quot;</span> <span class="operator">/</span><span class="operator">&gt;</span>
      <span class="operator">&lt;</span>file source<span class="operator">=</span><span class="string">&quot;project.pro&quot;</span> target<span class="operator">=</span><span class="string">&quot;%ProjectName%.pro&quot;</span> openproject<span class="operator">=</span><span class="string">&quot;true&quot;</span> <span class="operator">/</span><span class="operator">&gt;</span>
      <span class="operator">&lt;</span>file source<span class="operator">=</span><span class="string">&quot;icon.png&quot;</span> target<span class="operator">=</span><span class="string">&quot;%ProjectName%.png&quot;</span> binary<span class="operator">=</span><span class="string">&quot;true&quot;</span> <span class="operator">/</span><span class="operator">&gt;</span>

</pre>
<ul>
<li><code>source</code> specifies the file to copy to the project. The files must be located in the wizard folder.</li>
<li><code>openeditor</code> indicates that the file is to be opened in an editor after the wizard has finished.</li>
<li><code>binary</code> indicates that the file is a binary file (for example, an image file). It is to be copied to the target folder as is. Placeholders are not replaced with values.</li>
<li><code>target</code> specifies the new filename for the file. The <code>%ProjectName%</code> variable is replaced with the string that users specify in the <b>Name</b> field on the first page of the wizard.</li>
<li><code>openproject</code> indicates that the file is a project file which is to be opened after the wizard has finished.</li>
</ul>
<p>See also <a href="creator-project-wizards-xml.html#processing-template-files">Processing Template Files</a>.</p>
</li>
<li>The following code creates a page that specifies settings for the project:<pre class="cpp">

  <span class="operator">&lt;</span><span class="operator">!</span><span class="operator">-</span><span class="operator">-</span> Create a <span class="number">2nd</span> wizard page with parameters <span class="operator">-</span><span class="operator">-</span><span class="operator">&gt;</span>
  <span class="operator">&lt;</span>fieldpagetitle<span class="operator">&gt;</span>Hello World Parameters<span class="operator">&lt;</span><span class="operator">/</span>fieldpagetitle<span class="operator">&gt;</span>
  <span class="operator">&lt;</span>fieldpagetitle xml:lang<span class="operator">=</span><span class="string">&quot;de&quot;</span><span class="operator">&gt;</span>Hallo Welt Parameter<span class="operator">&lt;</span><span class="operator">/</span>fieldpagetitle<span class="operator">&gt;</span>
  <span class="operator">&lt;</span>fields<span class="operator">&gt;</span>
      <span class="operator">&lt;</span>field mandatory<span class="operator">=</span><span class="string">&quot;true&quot;</span> name<span class="operator">=</span><span class="string">&quot;MESSAGE&quot;</span><span class="operator">&gt;</span>
          <span class="operator">&lt;</span>fieldcontrol <span class="keyword">class</span><span class="operator">=</span><span class="string">&quot;QLineEdit&quot;</span> validator<span class="operator">=</span><span class="char">'^[^&quot;]+$'</span>  defaulttext<span class="operator">=</span><span class="string">&quot;Hello world!&quot;</span> placeholdertext<span class="operator">=</span><span class="string">&quot;Enter a message&quot;</span><span class="operator">/</span><span class="operator">&gt;</span>
          <span class="operator">&lt;</span>fielddescription<span class="operator">&gt;</span>Hello world message:<span class="operator">&lt;</span><span class="operator">/</span>fielddescription<span class="operator">&gt;</span>
          <span class="operator">&lt;</span>fielddescription xml:lang<span class="operator">=</span><span class="string">&quot;de&quot;</span><span class="operator">&gt;</span>Hallo<span class="operator">-</span>Welt<span class="operator">-</span>Nachricht:<span class="operator">&lt;</span><span class="operator">/</span>fielddescription<span class="operator">&gt;</span>
      <span class="operator">&lt;</span><span class="operator">/</span>field<span class="operator">&gt;</span>
  <span class="operator">&lt;</span><span class="operator">/</span>fields<span class="operator">&gt;</span>

</pre>
<ul>
<li><code>fieldpagetitle</code> specifies the title of the page.</li>
<li><code>fields</code> specifies the user interface objects on the page.</li>
<li><code>field</code> specifies one object. You can use a set of interface objects from <a href="http://doc.qt.io/qt-5/qtwidgets-module.html">QtWidgets</a> classes, derived from <a href="http://doc.qt.io/qt-5/qwidget.html">QWidget</a>, to create fields. This example uses <a href="http://doc.qt.io/qt-5/qlineedit.html">QLineEdit</a> to create an input field. For more information about the objects that you can add, see <a href="creator-project-wizards-xml.html#supported-widgets">Supported Widgets</a>.</li>
<li><code>mandatory</code> specifies whether the field is mandatory (<code>true</code> or <code>false</code>). For more information, see <a href="http://doc.qt.io/qt-5/qwizardpage.html#registerField">QWizardPage::registerField</a>().</li>
<li><code>name</code> specifies a name that you can use as a placeholder variable in the template file (for example, <code>%MESSAGE%</code>).</li>
<li><code>class</code> specifies the type of the <code>fieldcontrol</code>. The XML attributes that you can specify for the field depend on the field type.</li>
<li>For a <a href="http://doc.qt.io/qt-5/qlineedit.html">QLineEdit</a>, <code>validator</code> specifies a regular expression to check the characters allowed in the field.</li>
<li><code>defaulttext</code> specifies text that appears in the field by default.</li>
<li>For a <a href="http://doc.qt.io/qt-5/qlineedit.html">QLineEdit</a>, <code>placeholdertext</code> specifies placeholder text that appears in the field.</li>
<li><code>fielddescription</code> specifies the field name that appears on the wizard page.</li>
</ul>
</li>
</ol>
<a name="creating-class-wizards"></a>
<h2 id="creating-class-wizards">Creating Class Wizards</h2>
<p>The wizard.xml file for a class wizard is very similar to that for a project wizard. The differences are discussed below.</p>
<p>To create a class wizard:</p>
<ol class="1" type="1"><li>The following code specifies settings for the wizard:<pre class="cpp">

  <span class="operator">&lt;</span>wizard version<span class="operator">=</span><span class="string">&quot;1&quot;</span> kind<span class="operator">=</span><span class="string">&quot;class&quot;</span> id<span class="operator">=</span><span class="string">&quot;A.ListModel&quot;</span> category<span class="operator">=</span><span class="string">&quot;B.CustomClasses&quot;</span><span class="operator">&gt;</span>

     <span class="operator">&lt;</span>description<span class="operator">&gt;</span>Creates a <span class="type"><a href="http://doc.qt.io/qt-5/qabstractlistmodel.html">QAbstractListModel</a></span> implementation<span class="operator">.</span><span class="operator">&lt;</span><span class="operator">/</span>description<span class="operator">&gt;</span>
     <span class="operator">&lt;</span>description xml:lang<span class="operator">=</span><span class="string">&quot;de&quot;</span><span class="operator">&gt;</span>Erzeugt eine Implementierung von <span class="type"><a href="http://doc.qt.io/qt-5/qabstractlistmodel.html">QAbstractListModel</a></span><span class="operator">.</span><span class="operator">&lt;</span><span class="operator">/</span>description<span class="operator">&gt;</span>

     <span class="operator">&lt;</span>displayname<span class="operator">&gt;</span><span class="type"><a href="http://doc.qt.io/qt-5/qabstractlistmodel.html">QAbstractListModel</a></span> implementation<span class="operator">&lt;</span><span class="operator">/</span>displayname<span class="operator">&gt;</span>
     <span class="operator">&lt;</span>displayname xml:lang<span class="operator">=</span><span class="string">&quot;de&quot;</span><span class="operator">&gt;</span>Implementierung von <span class="type"><a href="http://doc.qt.io/qt-5/qabstractlistmodel.html">QAbstractListModel</a></span><span class="operator">&lt;</span><span class="operator">/</span>displayname<span class="operator">&gt;</span>

     <span class="operator">&lt;</span>displaycategory<span class="operator">&gt;</span>Custom Classes<span class="operator">&lt;</span><span class="operator">/</span>displaycategory<span class="operator">&gt;</span>
     <span class="operator">&lt;</span>displaycategory xml:lang<span class="operator">=</span><span class="string">&quot;de&quot;</span><span class="operator">&gt;</span>Benutzerdefinierte Klassen<span class="operator">&lt;</span><span class="operator">/</span>displaycategory<span class="operator">&gt;</span>

</pre>
<p>For more information about the elements and their values, see <a href="creator-project-wizards-xml.html#creating-xml-based-project-wizards">Creating XML-Based Project Wizards</a>.</p>
</li>
<li>The following code specifies the files to add to the project:<pre class="cpp">

  <span class="operator">&lt;</span>files<span class="operator">&gt;</span>
      <span class="operator">&lt;</span>file source<span class="operator">=</span><span class="string">&quot;listmodel.cpp&quot;</span> target<span class="operator">=</span><span class="string">&quot;%ClassName:l%.%CppSourceSuffix%&quot;</span>  openeditor<span class="operator">=</span><span class="string">&quot;true&quot;</span> <span class="operator">/</span><span class="operator">&gt;</span>
      <span class="operator">&lt;</span>file source<span class="operator">=</span><span class="string">&quot;listmodel.h&quot;</span> target<span class="operator">=</span><span class="string">&quot;%ClassName:l%.%CppHeaderSuffix%&quot;</span>  openeditor<span class="operator">=</span><span class="string">&quot;true&quot;</span> <span class="operator">/</span><span class="operator">&gt;</span>
  <span class="operator">&lt;</span><span class="operator">/</span>files<span class="operator">&gt;</span>

</pre>
<p>Here, <code>target</code> contains the following variables that are used to construct the filename:</p>
<ul>
<li><code>%ClassName:l%</code> is replaced with the value of the <code>ClassName</code> field. The modifier <code>l</code> converts the string to lower case, to observe Qt conventions.</li>
<li><code>%CppSourceSuffix%</code> and <code>%CppHeaderSuffix%</code> are pre-defined. For more information, see <a href="creator-project-wizards-xml.html#pre-defined-standard-variables">Pre-defined Standard Variables</a>.</li>
</ul>
<pre class="cpp">

  <span class="operator">&lt;</span><span class="operator">!</span><span class="operator">-</span><span class="operator">-</span> Create parameter wizard page <span class="operator">-</span><span class="operator">-</span><span class="operator">&gt;</span>

  <span class="operator">&lt;</span>fieldpagetitle<span class="operator">&gt;</span>ListModel parameters<span class="operator">&lt;</span><span class="operator">/</span>fieldpagetitle<span class="operator">&gt;</span>
  <span class="operator">&lt;</span>fieldpagetitle xml:lang<span class="operator">=</span><span class="string">&quot;de&quot;</span><span class="operator">&gt;</span>Parameter des ListModel<span class="operator">&lt;</span><span class="operator">/</span>fieldpagetitle<span class="operator">&gt;</span>
  <span class="operator">&lt;</span>fields<span class="operator">&gt;</span>
      <span class="operator">&lt;</span>field name<span class="operator">=</span><span class="string">&quot;ClassName&quot;</span><span class="operator">&gt;</span>

          <span class="operator">&lt;</span>fieldcontrol <span class="keyword">class</span><span class="operator">=</span><span class="string">&quot;QLineEdit&quot;</span> validator<span class="operator">=</span><span class="string">&quot;^[a-zA-Z0-9_]+$&quot;</span> defaulttext<span class="operator">=</span><span class="string">&quot;MyListModel&quot;</span> <span class="operator">/</span><span class="operator">&gt;</span>

          <span class="operator">&lt;</span>fielddescription<span class="operator">&gt;</span>Class name:<span class="operator">&lt;</span><span class="operator">/</span>fielddescription<span class="operator">&gt;</span>
          <span class="operator">&lt;</span>fielddescription xml:lang<span class="operator">=</span><span class="string">&quot;de&quot;</span><span class="operator">&gt;</span>Klassenname:<span class="operator">&lt;</span><span class="operator">/</span>fielddescription<span class="operator">&gt;</span>
      <span class="operator">&lt;</span><span class="operator">/</span>field<span class="operator">&gt;</span>
      <span class="operator">&lt;</span>field name<span class="operator">=</span><span class="string">&quot;Datatype&quot;</span><span class="operator">&gt;</span>
          <span class="operator">&lt;</span>fieldcontrol <span class="keyword">class</span><span class="operator">=</span><span class="string">&quot;QComboBox&quot;</span> defaultindex<span class="operator">=</span><span class="string">&quot;0&quot;</span><span class="operator">&gt;</span>
              <span class="operator">&lt;</span>comboentries<span class="operator">&gt;</span>
                  <span class="operator">&lt;</span>comboentry value<span class="operator">=</span><span class="string">&quot;QString&quot;</span><span class="operator">&gt;</span>
                      <span class="operator">&lt;</span>comboentrytext<span class="operator">&gt;</span><span class="keyword">class</span> <span class="type"><a href="http://doc.qt.io/qt-5/qstring.html">QString</a></span><span class="operator">&lt;</span><span class="operator">/</span>comboentrytext<span class="operator">&gt;</span>
                      <span class="operator">&lt;</span>comboentrytext xml:lang<span class="operator">=</span><span class="string">&quot;de&quot;</span><span class="operator">&gt;</span>Klasse <span class="type"><a href="http://doc.qt.io/qt-5/qstring.html">QString</a></span><span class="operator">&lt;</span><span class="operator">/</span>comboentrytext<span class="operator">&gt;</span>
                  <span class="operator">&lt;</span><span class="operator">/</span>comboentry<span class="operator">&gt;</span>
              <span class="operator">&lt;</span>comboentry value<span class="operator">=</span><span class="string">&quot;int&quot;</span><span class="operator">&gt;</span>
                  <span class="operator">&lt;</span>comboentrytext<span class="operator">&gt;</span>Integer<span class="operator">&lt;</span><span class="operator">/</span>comboentrytext<span class="operator">&gt;</span>
                  <span class="operator">&lt;</span>comboentrytext xml:lang<span class="operator">=</span><span class="string">&quot;de&quot;</span><span class="operator">&gt;</span>Ganzzahlwert<span class="operator">&lt;</span><span class="operator">/</span>comboentrytext<span class="operator">&gt;</span>
              <span class="operator">&lt;</span><span class="operator">/</span>comboentry<span class="operator">&gt;</span>
          <span class="operator">&lt;</span><span class="operator">/</span>comboentries<span class="operator">&gt;</span>
          <span class="operator">&lt;</span><span class="operator">/</span>fieldcontrol<span class="operator">&gt;</span>
          <span class="operator">&lt;</span>fielddescription<span class="operator">&gt;</span>Data type:<span class="operator">&lt;</span><span class="operator">/</span>fielddescription<span class="operator">&gt;</span>
          <span class="operator">&lt;</span>fielddescription xml:lang<span class="operator">=</span><span class="string">&quot;de&quot;</span><span class="operator">&gt;</span>Datentyp:<span class="operator">&lt;</span><span class="operator">/</span>fielddescription<span class="operator">&gt;</span>
      <span class="operator">&lt;</span><span class="operator">/</span>field<span class="operator">&gt;</span>
  <span class="operator">&lt;</span><span class="operator">/</span>fields<span class="operator">&gt;</span>

</pre>
<p>In addition to <a href="http://doc.qt.io/qt-5/qlineedit.html">QLineEdit</a>, <a href="http://doc.qt.io/qt-5/qcombobox.html">QComboBox</a> is used in the class wizard to create a field. Specify the following XML attributes:</p>
<ul>
<li><code>defaultindex</code> specifies which comboentry is displayed by default. In the above example, &quot;0&quot; means that the first comboentry is the default value.</li>
<li><code>comboentries</code> specifies the options in the combobox.</li>
<li><code>value</code> specifies the type of each <code>comboentry</code>, <a href="http://doc.qt.io/qt-5/qstring.html">QString</a> or integer.</li>
<li><code>comboentrytext</code> specifies the text of the entry.</li>
</ul>
</li>
</ol>
<a name="supported-widgets"></a>
<h2 id="supported-widgets">Supported Widgets</h2>
<p>You can use the following interface objects to create fields in the wizards:</p>
<ul>
<li>PathChooser utility to set paths</li>
<li>Check boxes with text labels (<a href="http://doc.qt.io/qt-5/qcheckbox.html">QCheckBox</a>)</li>
<li>Combined button and popup lists (<a href="http://doc.qt.io/qt-5/qcombobox.html">QComboBox</a>)</li>
<li>One-line text editors (<a href="http://doc.qt.io/qt-5/qlineedit.html">QLineEdit</a>)</li>
<li>Multi-line rich text editors (<a href="http://doc.qt.io/qt-5/qtextedit.html">QTextEdit</a>)</li>
</ul>
<p>Using <a href="http://doc.qt.io/qt-5/qlineedit.html">QLineEdit</a> and <a href="http://doc.qt.io/qt-5/qcombobox.html">QComboBox</a> is described in the previous sections. The following sections show examples of using the other classes and describe the XML attributes that you can specify for the <code>fieldcontrol</code> element of a field in a particular <code>class</code>.</p>
<a name="path-choosers"></a>
<h3 id="path-choosers">Path Choosers</h3>
<pre class="cpp">

  <span class="operator">&lt;</span>field mandatory<span class="operator">=</span><span class="string">&quot;true&quot;</span> name<span class="operator">=</span><span class="string">&quot;QtCreatorSources&quot;</span><span class="operator">&gt;</span>
      <span class="operator">&lt;</span>fieldcontrol <span class="keyword">class</span><span class="operator">=</span><span class="string">&quot;Utils::PathChooser&quot;</span> defaulttext<span class="operator">=</span><span class="string">&quot;&quot;</span> expectedkind<span class="operator">=</span><span class="string">&quot;existingdirectory&quot;</span><span class="operator">/</span><span class="operator">&gt;</span>
          <span class="operator">&lt;</span>fielddescription<span class="operator">&gt;</span><span class="type"><a href="http://doc.qt.io/qt-5/qt.html">Qt</a></span> Creator sources:<span class="operator">&lt;</span><span class="operator">/</span>fielddescription<span class="operator">&gt;</span>
  <span class="operator">&lt;</span><span class="operator">/</span>field<span class="operator">&gt;</span>

</pre>
<p>The <code>defaulttext</code> attribute specifies text that appears in the field by default.</p>
<p>The text attribute <code>expectedkind</code> specifies which type of path is expected:</p>
<ul>
<li><code>any</code> accepts any kind of path.</li>
<li><code>file</code> expects a file.</li>
<li><code>directory</code> expects a directory.</li>
<li><code>existingdirectory</code> expects an existing directory.</li>
<li><code>command</code> expects an executable file.</li>
<li><code>existingcommand</code> expects an existing, executable file.</li>
</ul>
<a name="check-boxes"></a>
<h3 id="check-boxes">Check Boxes</h3>
<p>To make check boxes appear selected by default, set the <code>fieldcontrol</code> attribute <code>defaultvalue</code> to <code>true</code>. Any other value or omitting the attribute makes the check box appear not selected.</p>
<p>For example:</p>
<pre class="cpp">

  <span class="operator">&lt;</span>field name<span class="operator">=</span><span class="string">&quot;CONSOLE&quot;</span><span class="operator">&gt;</span>
      <span class="operator">&lt;</span>fieldcontrol <span class="keyword">class</span><span class="operator">=</span><span class="string">&quot;QCheckBox&quot;</span> defaultvalue<span class="operator">=</span><span class="string">&quot;true&quot;</span><span class="operator">/</span><span class="operator">&gt;</span>
      <span class="operator">&lt;</span>fielddescription<span class="operator">&gt;</span>Console application<span class="operator">&lt;</span><span class="operator">/</span>fielddescription<span class="operator">&gt;</span>
  <span class="operator">&lt;</span><span class="operator">/</span>field<span class="operator">&gt;</span>

</pre>
<p>For more examples about using check boxes, see <a href="creator-project-wizards-xml.html#processing-template-files">Processing Template Files</a>.</p>
<a name="text-editors"></a>
<h3 id="text-editors">Text Editors</h3>
<pre class="cpp">

  <span class="operator">&lt;</span>field name<span class="operator">=</span><span class="string">&quot;License&quot;</span><span class="operator">&gt;</span>
      <span class="operator">&lt;</span>fieldcontrol <span class="keyword">class</span><span class="operator">=</span><span class="string">&quot;QTextEdit&quot;</span> defaulttext<span class="operator">=</span><span class="string">&quot;Put your license text here&quot;</span> <span class="operator">/</span><span class="operator">&gt;</span>
          <span class="operator">&lt;</span>fielddescription<span class="operator">&gt;</span>License:<span class="operator">&lt;</span><span class="operator">/</span>fielddescription<span class="operator">&gt;</span>
  <span class="operator">&lt;</span><span class="operator">/</span>field<span class="operator">&gt;</span>

</pre>
<p>The <code>defaulttext</code> attribute specifies text that appears in the field by default.</p>
<p>The boolean attribute <code>acceptRichText</code> sets the property <a href="http://doc.qt.io/qt-5/qtextedit.html#acceptRichText-prop">QTextEdit::acceptRichText</a>. It is disabled by default (as opposed to the default value of <a href="http://doc.qt.io/qt-5/qtextedit.html#acceptRichText-prop">QTextEdit::acceptRichText</a>) to prevent pasting of rich text with formatting, which is not desirable for code templates.</p>
<a name="processing-template-files"></a>
<h2 id="processing-template-files">Processing Template Files</h2>
<p>When processing a template source file, placeholders specifying the field names in the format <code>%FIELDNAME%</code> are replaced by the values entered by the user. In addition, modifier characters are supported. For example, <code>%FIELDNAME:u%</code> specifies that the value is converted to upper case. This enables generating header guards for C++ header files.</p>
<p>The following modifier characters are supported:</p>
<ul>
<li><code>l</code> for lower case.</li>
<li><code>u</code> for upper case.</li>
<li><code>c</code> for upper case initial letter (&quot;project&quot; &gt; &quot;Project&quot;).</li>
</ul>
<p>In the <code>helloworld</code> example, the placeholder <code>%NETWORK%</code> is used together with the <a href="http://doc.qt.io/qt-5/qcheckbox.html">QCheckBox</a> class. The following line is added to the project file:</p>
<pre class="cpp">

  <span class="operator">%</span>NETWORK<span class="operator">%</span>QT <span class="operator">+</span><span class="operator">=</span> network

</pre>
<p>And the following field is specified in the wizard.xml:</p>
<pre class="cpp">

  <span class="operator">&lt;</span>field name<span class="operator">=</span><span class="string">&quot;NETWORK&quot;</span><span class="operator">&gt;</span>
      <span class="operator">&lt;</span>fieldcontrol <span class="keyword">class</span><span class="operator">=</span><span class="string">&quot;QCheckBox&quot;</span> truevalue<span class="operator">=</span><span class="string">&quot;&quot;</span> falsevalue<span class="operator">=</span><span class="string">&quot;# &quot;</span><span class="operator">/</span><span class="operator">&gt;</span>
      <span class="operator">&lt;</span>fielddescription<span class="operator">&gt;</span>Include network module<span class="operator">&lt;</span><span class="operator">/</span>fielddescription<span class="operator">&gt;</span>
      <span class="operator">&lt;</span>fielddescription xml:lang<span class="operator">=</span><span class="string">&quot;de&quot;</span><span class="operator">&gt;</span>Netzwerk<span class="operator">-</span>Modul verwenden<span class="operator">&lt;</span><span class="operator">/</span>fielddescription<span class="operator">&gt;</span>
  <span class="operator">&lt;</span><span class="operator">/</span>field<span class="operator">&gt;</span>

</pre>
<p>If the checkbox is checked, the placeholder is replaced by <code>truevalue</code>. If it is not checked, the placeholder is replaced by <code>falsevalue</code>.</p>
<p>You can use conditions to add sections of the file depending on field values. Use a syntax that is similar to C++ preprocessing, as demonstrated in the project file of the <code>helloworld</code> example:</p>
<pre class="cpp">

  @<span class="keyword">if</span> <span class="string">&quot;%SCRIPT%&quot;</span> <span class="operator">=</span><span class="operator">=</span> <span class="string">&quot;true&quot;</span>
  QT <span class="operator">+</span><span class="operator">=</span> script
  @endif

</pre>
<p>The value of the Boolean (<a href="http://doc.qt.io/qt-5/qcheckbox.html">QCheckBox</a>) field labeled <code>SCRIPT</code> determines whether the script module is added. The expressions must expand to valid Javascript expressions after field replacement.</p>
<p>For example, the following field is specified in the wizard.xml:</p>
<pre class="cpp">

  <span class="operator">&lt;</span>field name<span class="operator">=</span><span class="string">&quot;SCRIPT&quot;</span><span class="operator">&gt;</span>
      <span class="operator">&lt;</span>fieldcontrol <span class="keyword">class</span><span class="operator">=</span><span class="string">&quot;QCheckBox&quot;</span><span class="operator">/</span><span class="operator">&gt;</span>
      <span class="operator">&lt;</span>fielddescription<span class="operator">&gt;</span>Include script module<span class="operator">&lt;</span><span class="operator">/</span>fielddescription<span class="operator">&gt;</span>
      <span class="operator">&lt;</span>fielddescription xml:lang<span class="operator">=</span><span class="string">&quot;de&quot;</span><span class="operator">&gt;</span>Script<span class="operator">-</span>Modul verwenden<span class="operator">&lt;</span><span class="operator">/</span>fielddescription<span class="operator">&gt;</span>
  <span class="operator">&lt;</span><span class="operator">/</span>field<span class="operator">&gt;</span>

</pre>
<a name="pre-defined-standard-variables"></a>
<h2 id="pre-defined-standard-variables">Pre-defined Standard Variables</h2>
<p>In addition to the field values entered by the user, you can use the following pre-defined standard values:</p>
<ul>
<li><code>%ProjectName%</code> is replaced by the name of the project in the case of project wizards.</li>
<li><code>%Path%</code> is replaced by the path to the target directory. For classes, this is the directory, where the files are created. For project wizards, an additional subdirectory named after the project is created.</li>
<li><code>%TargetPath%</code> is replaced by the path to the directory where the actual files are created. For non-project wizards, it is identical to <code>%Path%</code>. For project wizards, it is <code>%Path%/%ProjectName%</code>.</li>
<li><code>%CppSourceSuffix%</code> is replaced by the default source suffix, which is defined in Qt Creator in <b>Tools &gt; Options &gt; C++ &gt; File Naming</b>. For example, if users enter <b>MyClass</b>, the filename becomes myclass.cpp when the project is created.</li>
<li><code>%CppHeaderSuffix%</code> is replaced by the default header suffix, which is also defined in <b>File Naming</b>.</li>
<li><code>%CurrentDate%</code> is replaced by the current date in the format <code>YYYY-MM-DD</code> as specified by ISO 8601.</li>
<li><code>%CurrentTime%</code> is replaced by the current time in the format <code>HH:MM:SS</code> as specified by ISO 8601.</li>
<li><code>%CurrentDate:Locale%</code> is replaced by the current date in the short format specified by the application's locale.</li>
<li><code>%CurrentTime:Locale%</code> is replaced by the current time in the short format specified by the application's locale.</li>
<li><code>%CurrentDate:ISO%</code> is replaced by the current date in the format <code>YYYY-MM-DD</code> as specified by ISO 8601.</li>
<li><code>%CurrentTime:ISO%</code> is replaced by the current time in the format <code>HH:MM:SS</code> as specified by ISO 8601.</li>
<li><code>%CurrentDate:RFC%</code> is replaced by the current date in the format <code>DD Mon YYYY</code>, where <code>Mon</code> is the three letter month name, as specified by RFC 2822.</li>
<li><code>%CurrentTime:RFC%</code> is replaced by the current time in the format <code>HH:MM:SS</code> as specified by RFC 2822.</li>
</ul>
<a name="validating-user-input"></a>
<h2 id="validating-user-input">Validating User Input</h2>
<p>You can specify validation rules for user input. The rules consist of a Boolean JavaScript expression and an error message. The placeholders in them are replaced with values before they are evaluated or displayed.</p>
<p>Consider the following rule used in the <a href="creator-project-wizards-xml.html#creating-class-wizards">Creating Class Wizards</a> example:</p>
<pre class="cpp">

  <span class="operator">&lt;</span>validationrules<span class="operator">&gt;</span>
      <span class="operator">&lt;</span>validationrule condition<span class="operator">=</span><span class="char">'&quot;%ClassName%&quot; != &quot;QAbstractListModel&quot;'</span><span class="operator">&gt;</span>
          <span class="operator">&lt;</span>message<span class="operator">&gt;</span><span class="operator">%</span>ClassName<span class="operator">%</span> cannot be used as <span class="keyword">class</span> name<span class="operator">.</span><span class="operator">&lt;</span><span class="operator">/</span>message<span class="operator">&gt;</span>
          <span class="operator">&lt;</span>message xml:lang<span class="operator">=</span><span class="string">&quot;de&quot;</span><span class="operator">&gt;</span><span class="operator">%</span>ClassName<span class="operator">%</span> kann nicht als Klassenname verwendet werden<span class="operator">.</span><span class="operator">&lt;</span><span class="operator">/</span>message<span class="operator">&gt;</span>
      <span class="operator">&lt;</span><span class="operator">/</span>validationrule<span class="operator">&gt;</span>
  <span class="operator">&lt;</span><span class="operator">/</span>validationrules<span class="operator">&gt;</span>

</pre>
<p>It ensures that the class name entered by the user does not match the name of the base class. If the validation fails, a red label displaying the message appears at the bottom of the wizard page.</p>
</div>
<!-- @@@creator-project-wizards-xml.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="creator-project-wizards-json.html">Adding JSON-Based Wizards</a>
<span class="naviSeparator">  &#9702;  </span>
<a class="nextPage" href="creator-version-control.html">Using Version Control Systems</a>
</p>
        </div>
       </div>
   </div>
   </div>
</div>
<div class="footer">
   <p>
   <acronym title="Copyright">&copy;</acronym> 2019 The Qt Company Ltd.
   Documentation contributions included herein are the copyrights of
   their respective owners.<br>    The documentation provided herein is licensed under the terms of the    <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation    License version 1.3</a> as published by the Free Software Foundation.<br>    Qt and respective logos are trademarks of The Qt Company Ltd.     in Finland and/or other countries worldwide. All other trademarks are property
   of their respective owners. </p>
</div>
</body>
</html>
